<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Search API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'search-search.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-search.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-search.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/search-search.html" rel="nofollow" target="_blank">../en/search-search.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="search.html">Search APIs</a></span>
»
<span class="breadcrumb-node">Search API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search.html">« Search APIs</a>
</span>
<span class="next">
<a href="search-request-body.html">Request Body Search »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="search-search"></a>Search API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h2>
</div></div></div>

<p>Returns search hits that match the query defined in the request.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /twitter/_search</pre>
</div>
<div class="console_widget" data-snippet="snippets/1889.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-search-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">GET /&lt;index&gt;/_search</code></p>
<p><code class="literal">GET /_search</code></p>
<p><code class="literal">POST /&lt;index&gt;/_search</code></p>
<p><code class="literal">POST /_search</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-search-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Allows you to execute a search query and get back search hits that match the
query. You can provide search queries using the <a class="xref" href="search-search.html#search-api-query-params-q"><code class="literal">q</code>
query string parameter</a> or <a class="xref" href="search-request-body.html" title="Request Body Search">request body</a>.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-search-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;index&gt;</code>
</span>
</dt>
<dd>
(Optional, string) Comma-separated list or wildcard expression of index names
used to limit the request.
</dd>
</dl>
</div>
</div>

<div class="section child_attributes">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-search-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>Several options for this API can be specified using a query parameter
or a request body parameter. If both parameters are specified, only the query
parameter is used.</p>
</div>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">allow_no_indices</code>
</span>
</dt>
<dd>
<p>
(Optional, boolean) If <code class="literal">true</code>,
the request does <span class="strong strong"><strong>not</strong></span> return an error
if a wildcard expression
or <code class="literal">_all</code> value retrieves only missing or closed indices.
</p>
<p>This parameter also applies to <a class="xref" href="indices-aliases.html" title="Update index alias API">index aliases</a>
that point to a missing or closed index.</p>
<p>Defaults to <code class="literal">true</code>.</p>
</dd>
</dl>
</div>
<div class="variablelist">
<a id="search-partial-responses"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">allow_partial_search_results</code>
</span>
</dt>
<dd>
<p>
(Optional, boolean)
If <code class="literal">true</code>, returns partial results if there are request timeouts or
<a class="xref" href="docs-replication.html#shard-failures" title="Shard failures">shard failures</a>. If <code class="literal">false</code>, returns an error with
no partial results. Defaults to <code class="literal">true</code>.
</p>
<p>To override the default for this field, set the
<code class="literal">search.default_allow_partial_results</code> cluster setting to <code class="literal">false</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">batched_reduce_size</code>
</span>
</dt>
<dd>
(Optional, integer) The number of shard results that should be reduced at once
on the coordinating node. This value should be used as a protection mechanism
to reduce the memory overhead per search request if the potential number of
shards in the request can be large. Defaults to <code class="literal">512</code>.
</dd>
</dl>
</div>
<div class="variablelist">
<a id="ccs-minimize-roundtrips"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">ccs_minimize_roundtrips</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, network round-trips between the
coordinating node and the remote clusters are minimized when executing
cross-cluster search (CCS) requests. See <a class="xref" href="modules-cross-cluster-search.html#ccs-network-delays" title="How cross-cluster search handles network delays">How cross-cluster search handles network delays</a>. Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">docvalue_fields</code>
</span>
</dt>
<dd>
(Optional, string) A comma-separated list of fields to return as the docvalue
representation of a field for each hit.
</dd>
<dt>
<span class="term">
<code class="literal">expand_wildcards</code>
</span>
</dt>
<dd>
<p>(Optional, string) Controls what kind of indices that wildcard expressions can
expand to. Multiple values are accepted when separated by a comma, as in
<code class="literal">open,hidden</code>. Valid values are:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">all</code>
</span>
</dt>
<dd>
Expand to open and closed indices, including <a class="xref" href="index-modules.html#index-hidden">hidden indices</a>.
</dd>
<dt>
<span class="term">
<code class="literal">open</code>
</span>
</dt>
<dd>
Expand only to open indices.
</dd>
<dt>
<span class="term">
<code class="literal">closed</code>
</span>
</dt>
<dd>
Expand only to closed indices.
</dd>
<dt>
<span class="term">
<code class="literal">hidden</code>
</span>
</dt>
<dd>
Expansion of wildcards will include <a class="xref" href="index-modules.html#index-hidden">hidden indices</a>.
Must be combined with <code class="literal">open</code>, <code class="literal">closed</code>, or both.
</dd>
<dt>
<span class="term">
<code class="literal">none</code>
</span>
</dt>
<dd>
Wildcard expressions are not accepted.
</dd>
</dl>
</div>
<p>Defaults to <code class="literal">open</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">explain</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, returns detailed information about score
computation as part of a hit. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">from</code>
</span>
</dt>
<dd>
<p>
(Optional, integer) Starting document offset. Defaults to <code class="literal">0</code>.
</p>
<p>By default, you cannot page through more than 10,000 documents using the <code class="literal">from</code>
and <code class="literal">size</code> parameters. This limit is set using the
<a class="xref" href="index-modules.html#index-max-result-window"><code class="literal">index.max_result_window</code></a> index setting.</p>
<p>Deep paging or requesting many results at once can result in slow searches.
Results are sorted before being returned. Because search requests usually span
multiple shards, each shard must generate its own sorted results. These separate
results must then be combined and sorted to ensure that the overall order is
correct.</p>
<p>As an alternative to deep paging, we recommend using
<a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">scroll</a> or the
<a class="xref" href="search-request-body.html#request-body-search-search-after" title="Search After"><code class="literal">search_after</code></a> parameter.</p>
</dd>
<dt>
<span class="term">
<code class="literal">ignore_throttled</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, concrete, expanded or aliased indices will be
ignored when frozen. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ignore_unavailable</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, missing or closed indices are not included in the
response. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">max_concurrent_shard_requests</code>
</span>
</dt>
<dd>
(Optional, integer) Defines the number of concurrent shard requests per node
this search executes concurrently. This value should be used to limit the
impact of the search on the cluster in order to limit the number of concurrent
shard requests. Defaults to <code class="literal">5</code>.
</dd>
<dt>
<span class="term">
<code class="literal">pre_filter_shard_size</code>
</span>
</dt>
<dd>
<p>
(Optional, integer) Defines a threshold that enforces a pre-filter roundtrip
to prefilter search shards based on query rewriting if the number of shards
the search request expands to exceeds the threshold. This filter roundtrip can
limit the number of shards significantly if for instance a shard can not match
any documents based on its rewrite method ie. if date filters are mandatory
to match but the shard bounds and the query are disjoint.
When unspecified, the pre-filter phase is executed if any of these conditions is met:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The request targets more than <code class="literal">128</code> shards.
</li>
<li class="listitem">
The request targets one or more read-only index.
</li>
<li class="listitem">
The primary sort of the query targets an indexed field.
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">preference</code>
</span>
</dt>
<dd>
(Optional, string) Specifies the node or shard the operation should be
performed on. Random by default.
</dd>
</dl>
</div>
<div class="variablelist">
<a id="search-api-query-params-q"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">q</code>
</span>
</dt>
<dd>
<p>
(Optional, string) Query in the Lucene query string syntax.
</p>
<p>You can use the <code class="literal">q</code> parameter to run a query parameter search. Query parameter
searches do not support the full Elasticsearch <a class="xref" href="query-dsl.html" title="Query DSL">Query DSL</a> but are handy for
testing.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">q</code> parameter overrides the <a class="xref" href="search-search.html#request-body-search-query"><code class="literal">query</code></a>
parameter in the request body. If both parameters are specified, documents
matching the <code class="literal">query</code> request body parameter are not returned.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">request_cache</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, the caching of search results is enabled for
requests where <code class="literal">size</code> is <code class="literal">0</code>. See <a class="xref" href="shard-request-cache.html" title="Shard request cache settings">Shard request cache settings</a>. Defaults to index
level settings.
</dd>
<dt>
<span class="term">
<code class="literal">rest_total_hits_as_int</code>
</span>
</dt>
<dd>
(Optional, boolean) Indicates whether hits.total should be rendered as an
integer or an object in the rest search response. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">routing</code>
</span>
</dt>
<dd>
(Optional, string) Target the specified primary shard.
</dd>
</dl>
</div>
<div class="variablelist">
<a id="search-api-scroll-query-param"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">scroll</code>
</span>
</dt>
<dd>
<p>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time value</a>)
Period to retain the <a class="xref" href="search-request-body.html#scroll-search-context" title="Keeping the search context alive">search context</a> for scrolling. See
<a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">Scroll</a>.
</p>
<p>By default, this value cannot exceed <code class="literal">1d</code> (24 hours). You can change
this limit using the <code class="literal">search.max_keep_alive</code> cluster-level setting.</p>
</dd>
<dt>
<span class="term">
<code class="literal">search_type</code>
</span>
</dt>
<dd>
<p>
(Optional, string) The type of the search operation. Available options:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">query_then_fetch</code>
</li>
<li class="listitem">
<code class="literal">dfs_query_then_fetch</code>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">seq_no_primary_term</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, returns sequence number and primary term of the
last modification of each hit. See <a class="xref" href="optimistic-concurrency-control.html" title="Optimistic concurrency control">Optimistic concurrency control</a>.
</dd>
<dt>
<span class="term">
<code class="literal">size</code>
</span>
</dt>
<dd>
<p>
(Optional, integer) Defines the number of hits to return. Defaults to <code class="literal">10</code>.
</p>
<p>By default, you cannot page through more than 10,000 documents using the <code class="literal">from</code>
and <code class="literal">size</code> parameters. This limit is set using the
<a class="xref" href="index-modules.html#index-max-result-window"><code class="literal">index.max_result_window</code></a> index setting.</p>
<p>Deep paging or requesting many results at once can result in slow searches.
Results are sorted before being returned. Because search requests usually span
multiple shards, each shard must generate its own sorted results. These separate
results must then be combined and sorted to ensure that the overall order is
correct.</p>
<p>As an alternative to deep paging, we recommend using
<a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">scroll</a> or the
<a class="xref" href="search-request-body.html#request-body-search-search-after" title="Search After"><code class="literal">search_after</code></a> parameter.</p>
<p>If the <a class="xref" href="search-search.html#search-api-scroll-query-param"><code class="literal">scroll</code> parameter</a> is specified, this
value cannot be <code class="literal">0</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">sort</code>
</span>
</dt>
<dd>
(Optional, string) A comma-separated list of &lt;field&gt;:&lt;direction&gt; pairs.
</dd>
<dt>
<span class="term">
<code class="literal">_source</code>
</span>
</dt>
<dd>
<p>
(Optional)
Indicates which <a class="xref" href="mapping-source-field.html" title="_source field">source fields</a> are returned for matching
documents. These fields are returned in the <code class="literal">hits._source</code> property of
the search response. Defaults to <code class="literal">true</code>.
</p>
<details open>
<summary class="title">Valid values for <code class="literal">_source</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">true</code>
</span>
</dt>
<dd>
(boolean)
The entire document source is returned.
</dd>
<dt>
<span class="term">
<code class="literal">false</code>
</span>
</dt>
<dd>
(boolean)
The document source is not returned.
</dd>
<dt>
<span class="term">
<code class="literal">&lt;string&gt;</code>
</span>
</dt>
<dd>
(string)
Comma-separated list of source fields to return.
Wildcard (<code class="literal">*</code>) patterns are supported.
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">_source_excludes</code>
</span>
</dt>
<dd>
<p>
(Optional, string)
A comma-separated list of <a class="xref" href="mapping-source-field.html" title="_source field">source fields</a> to exclude from
the response.
</p>
<p>You can also use this parameter to exclude fields from the subset specified in
<code class="literal">_source_includes</code> query parameter.</p>
<p>If the <code class="literal">_source</code> parameter is <code class="literal">false</code>, this parameter is ignored.</p>
</dd>
<dt>
<span class="term">
<code class="literal">_source_includes</code>
</span>
</dt>
<dd>
<p>
(Optional, string)
A comma-separated list of <a class="xref" href="mapping-source-field.html" title="_source field">source fields</a> to
include in the response.
</p>
<p>If this parameter is specified, only these source fields are returned. You can
exclude fields from this subset using the <code class="literal">_source_excludes</code> query parameter.</p>
<p>If the <code class="literal">_source</code> parameter is <code class="literal">false</code>, this parameter is ignored.</p>
</dd>
<dt>
<span class="term">
<code class="literal">stats</code>
</span>
</dt>
<dd>
(Optional, string) Specific <code class="literal">tag</code> of the request for logging and statistical
purposes.
</dd>
<dt>
<span class="term">
<code class="literal">stored_fields</code>
</span>
</dt>
<dd>
<p>
(Optional, string) A comma-separated list of stored fields to return as part
of a hit. If no fields are specified, no stored fields are included in the
response.
</p>
<p>If this field is specified, the <code class="literal">_source</code> parameter defaults to <code class="literal">false</code>. You can
pass <code class="literal">_source: true</code> to return both source fields and
stored fields in the search response.</p>
</dd>
<dt>
<span class="term">
<code class="literal">suggest_field</code>
</span>
</dt>
<dd>
(Optional, string) Specifies which field to use for suggestions.
</dd>
<dt>
<span class="term">
<code class="literal">suggest_text</code>
</span>
</dt>
<dd>
(Optional, string) The source text for which the suggestions should be
returned.
</dd>
<dt>
<span class="term">
<code class="literal">terminate_after</code>
</span>
</dt>
<dd>
<p>
(Optional, integer) The maximum number of documents to collect for each shard,
upon reaching which the query execution will terminate early.
</p>
<p>Defaults to <code class="literal">0</code>, which does not terminate query execution early.</p>
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait
for a response. If no response is received before the timeout expires, the
request fails and returns an error. Defaults to no timeout.
</dd>
<dt>
<span class="term">
<code class="literal">track_scores</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, calculate and return document scores, even if
the scores are not used for sorting. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">track_total_hits</code>
</span>
</dt>
<dd>
<p>
(Optional, integer or boolean)
Number of hits matching the query to count accurately. Defaults to <code class="literal">10000</code>.
</p>
<p>If <code class="literal">true</code>, the default value is used. If <code class="literal">false</code>, the response does not
include the total number of hits matching the query.</p>
</dd>
<dt>
<span class="term">
<code class="literal">typed_keys</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, aggregation and suggester names are be prefixed
by their respective types in the response. Defaults to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">version</code>
</span>
</dt>
<dd>
(Optional, boolean)
If <code class="literal">true</code>, returns document version as part of a hit. Defaults to <code class="literal">false</code>.
</dd>
</dl>
</div>
</div>

<div class="section child_attributes">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-search-api-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<a id="search-docvalue-fields-param"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">docvalue_fields</code>
</span>
</dt>
<dd>
<p>
(Optional, array of strings and objects)
Array of wildcard (<code class="literal">*</code>) patterns. The request returns doc values for field names
matching these patterns in the <code class="literal">hits.fields</code> property of the response.
</p>
<p>You can specify items in the array as a string or object.
See <a class="xref" href="run-a-search.html#docvalue-fields" title="Doc value fields">Doc value fields</a>.</p>
<details>
<summary class="title">Properties of <code class="literal">docvalue_fields</code> objects</summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">field</code>
</span>
</dt>
<dd>
(Required, string)
Wildcard pattern. The request returns doc values for field names matching this
pattern.
</dd>
<dt>
<span class="term">
<code class="literal">format</code>
</span>
</dt>
<dd>
<p>
(Optional, string)
Format in which the doc values are returned.
</p>
<p>For <a class="xref" href="date.html" title="Date datatype">date fields</a>, you can specify a  date <a class="xref" href="mapping-date-format.html" title="format">date
<code class="literal">format</code></a>. For <a class="xref" href="number.html" title="Numeric datatypes">numeric fields</a> fields, you can specify a
<a href="https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html" class="ulink" target="_top">DecimalFormat
pattern</a>.</p>
<p>For other field datatypes, this parameter is not supported.</p>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
<div class="variablelist">
<a id="request-body-search-explain"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">explain</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, returns detailed information about score
computation as part of a hit. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">from</code>
</span>
</dt>
<dd>
<p>
(Optional, integer) Starting document offset. Defaults to <code class="literal">0</code>.
</p>
<p>By default, you cannot page through more than 10,000 documents using the <code class="literal">from</code>
and <code class="literal">size</code> parameters. This limit is set using the
<a class="xref" href="index-modules.html#index-max-result-window"><code class="literal">index.max_result_window</code></a> index setting.</p>
<p>Deep paging or requesting many results at once can result in slow searches.
Results are sorted before being returned. Because search requests usually span
multiple shards, each shard must generate its own sorted results. These separate
results must then be combined and sorted to ensure that the overall order is
correct.</p>
<p>As an alternative to deep paging, we recommend using
<a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">scroll</a> or the
<a class="xref" href="search-request-body.html#request-body-search-search-after" title="Search After"><code class="literal">search_after</code></a> parameter.</p>
</dd>
</dl>
</div>
<div class="variablelist">
<a id="request-body-search-query"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">query</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="query-dsl.html" title="Query DSL">query object</a>) Defines the search definition using the
<a class="xref" href="query-dsl.html" title="Query DSL">Query DSL</a>.
</dd>
</dl>
</div>
<div class="variablelist">
<a id="request-body-search-seq-no-primary-term"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">seq_no_primary_term</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, returns sequence number and primary term of the
last modification of each hit. See <a class="xref" href="optimistic-concurrency-control.html" title="Optimistic concurrency control">Optimistic concurrency control</a>.
</dd>
<dt>
<span class="term">
<code class="literal">size</code>
</span>
</dt>
<dd>
<p>
(Optional, integer) The number of hits to return. Defaults to <code class="literal">10</code>.
</p>
<p>By default, you cannot page through more than 10,000 documents using the <code class="literal">from</code>
and <code class="literal">size</code> parameters. This limit is set using the
<a class="xref" href="index-modules.html#index-max-result-window"><code class="literal">index.max_result_window</code></a> index setting.</p>
<p>Deep paging or requesting many results at once can result in slow searches.
Results are sorted before being returned. Because search requests usually span
multiple shards, each shard must generate its own sorted results. These separate
results must then be combined and sorted to ensure that the overall order is
correct.</p>
<p>As an alternative to deep paging, we recommend using
<a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">scroll</a> or the
<a class="xref" href="search-request-body.html#request-body-search-search-after" title="Search After"><code class="literal">search_after</code></a> parameter.</p>
<p>If the <a class="xref" href="search-search.html#search-api-scroll-query-param"><code class="literal">scroll</code> parameter</a> is specified, this
value cannot be <code class="literal">0</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">_source</code>
</span>
</dt>
<dd>
<p>
(Optional)
Indicates which <a class="xref" href="mapping-source-field.html" title="_source field">source fields</a> are returned for matching
documents. These fields are returned in the <code class="literal">hits._source</code> property of
the search response. Defaults to <code class="literal">true</code>.
</p>
<details open>
<summary class="title">Valid values for <code class="literal">_source</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">true</code>
</span>
</dt>
<dd>
(boolean)
The entire document source is returned.
</dd>
<dt>
<span class="term">
<code class="literal">false</code>
</span>
</dt>
<dd>
(boolean)
The document source is not returned.
</dd>
<dt>
<span class="term">
<code class="literal">&lt;wildcard_pattern&gt;</code>
</span>
</dt>
<dd>
(string or array of strings)
Wildcard (<code class="literal">*</code>) pattern or array of patterns containing source fields to return.
</dd>
<dt>
<span class="term">
<code class="literal">&lt;object&gt;</code>
</span>
</dt>
<dd>
<p>
(object)
Object containing a list of source fields to include or exclude.
</p>
<details open>
<summary class="title">Properties for <code class="literal">&lt;object&gt;</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">excludes</code>
</span>
</dt>
<dd>
<p>
(string or array of strings)
Wildcard (<code class="literal">*</code>) pattern or array of patterns containing source fields to exclude
from the response.
</p>
<p>You can also use this property to exclude fields from the subset specified in
<code class="literal">includes</code> property.</p>
</dd>
<dt>
<span class="term">
<code class="literal">includes</code>
</span>
</dt>
<dd>
<p>
(string or array of strings)
Wildcard (<code class="literal">*</code>) pattern or array of patterns containing source fields to return.
</p>
<p>If this property is specified, only these source fields are returned. You can
exclude fields from this subset using the <code class="literal">excludes</code> property.</p>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">terminate_after</code>
</span>
</dt>
<dd>
<p>
(Optional, integer) The maximum number of documents to collect for each shard,
upon reaching which the query execution will terminate early.
</p>
<p>Defaults to <code class="literal">0</code>, which does not terminate query execution early.</p>
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait
for a response. If no response is received before the timeout expires, the
request fails and returns an error. Defaults to no timeout.
</dd>
</dl>
</div>
<div class="variablelist">
<a id="request-body-search-version"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">version</code>
</span>
</dt>
<dd>
(Optional, boolean)
If <code class="literal">true</code>, returns document version as part of a hit. Defaults to <code class="literal">false</code>.
</dd>
</dl>
</div>
</div>

<div class="section child_attributes">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-api-response-body"></a>Response body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">_scroll_id</code>
</span>
</dt>
<dd>
<p>
(string)
Identifier for the search and its <a class="xref" href="search-request-body.html#scroll-search-context" title="Keeping the search context alive">search context</a>.
</p>
<p>You can use this scroll ID with the <a class="xref" href="scroll-api.html" title="Scroll API">scroll API</a> to retrieve the
next batch of search results for the request. See
<a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">Scroll</a>.</p>
<p>This parameter is only returned if the <a class="xref" href="search-search.html#search-api-scroll-query-param"><code class="literal">scroll</code>
query parameter</a> is specified in the request.</p>
</dd>
<dt>
<span class="term">
<code class="literal">took</code>
</span>
</dt>
<dd>
<p>(integer)
Milliseconds it took Elasticsearch to execute the request.</p>
<p>This value is calculated by measuring the time elapsed
between receipt of a request on the coordinating node
and the time at which the coordinating node is ready to send the response.</p>
<p>Took time includes:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Communication time between the coordinating node and data nodes
</li>
<li class="listitem">
Time the request spends in the <code class="literal">search</code> <a class="xref" href="modules-threadpool.html" title="Thread pools">thread pool</a>,
queued for execution
</li>
<li class="listitem">
Actual execution time
</li>
</ul>
</div>
<p>Took time does <span class="strong strong"><strong>not</strong></span> include:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Time needed to send the request to Elasticsearch
</li>
<li class="listitem">
Time needed to serialize the JSON response
</li>
<li class="listitem">
Time needed to send the response to a client
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">timed_out</code>
</span>
</dt>
<dd>
(boolean)
If <code class="literal">true</code>,
the request timed out before completion;
returned results may be partial or empty.
</dd>
<dt>
<span class="term">
<code class="literal">_shards</code>
</span>
</dt>
<dd>
<p>
(object)
Contains a count of shards used for the request.
</p>
<details open>
<summary class="title">Properties of <code class="literal">_shards</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">total</code>
</span>
</dt>
<dd>
(integer)
Total number of shards that require querying,
including unallocated shards.
</dd>
<dt>
<span class="term">
<code class="literal">successful</code>
</span>
</dt>
<dd>
(integer)
Number of shards that executed the request successfully.
</dd>
<dt>
<span class="term">
<code class="literal">skipped</code>
</span>
</dt>
<dd>
(integer)
Number of shards that skipped the request because a lightweight check
helped realize that no documents could possibly match on this shard. This
typically happens when a search request includes a range filter and the
shard only has values that fall outside of that range.
</dd>
<dt>
<span class="term">
<code class="literal">failed</code>
</span>
</dt>
<dd>
(integer)
Number of shards that failed to execute the request. Note that shards
that are not allocated will be considered neither successful nor failed.
Having <code class="literal">failed+successful</code> less than <code class="literal">total</code> is thus an indication that
some of the shards were not allocated.
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">hits</code>
</span>
</dt>
<dd>
<p>
(object)
Contains returned documents and metadata.
</p>
<details open>
<summary class="title">Properties of <code class="literal">hits</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">total</code>
</span>
</dt>
<dd>
<p>
(object)
Metadata about the number of returned documents.
</p>
<details open>
<summary class="title">Properties of <code class="literal">total</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">value</code>
</span>
</dt>
<dd>
(integer)
Total number of returned documents.
</dd>
<dt>
<span class="term">
<code class="literal">relation</code>
</span>
</dt>
<dd>
<p>
(string)
Indicates whether the number of returned documents in the <code class="literal">value</code>
parameter is accurate or a lower bound.
</p>
<details open>
<summary class="title">Values of <code class="literal">relation</code>:</summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">eq</code>
</span>
</dt>
<dd>
Accurate
</dd>
<dt>
<span class="term">
<code class="literal">gte</code>
</span>
</dt>
<dd>
Lower bound, including returned documents
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">max_score</code>
</span>
</dt>
<dd>
<p>
(float)
Highest returned <a class="xref" href="search-search.html#search-api-response-body-score">document <code class="literal">_score</code></a>.
</p>
<p>This value is <code class="literal">null</code> for requests that do not sort by <code class="literal">_score</code>.</p>
</dd>
</dl>
</div>
<div class="variablelist">
<a id="search-api-response-body-hits"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">hits</code>
</span>
</dt>
<dd>
<p>
(array of objects)
Array of returned document objects.
</p>
<details open>
<summary class="title">Properties of <code class="literal">hits</code> objects</summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">_index</code>
</span>
</dt>
<dd>
(string)
Name of the index containing the returned document.
</dd>
<dt>
<span class="term">
<code class="literal">_type</code>
</span>
</dt>
<dd>
<span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">6.0.0</span>]
<span class="Admonishment-detail">
Deprecated in 6.0.0. Mapping types are deprecated and will be removed in 8.0. See <a class="xref" href="removal-of-types.html" title="Removal of mapping types"><em>Removal of mapping types</em></a>.
</span>
</span>
(string)
Mapping type of the returned document.
</dd>
<dt>
<span class="term">
<code class="literal">_id</code>
</span>
</dt>
<dd>
(string)
Unique identifier for the returned document.
This ID is only unique within the returned index.
</dd>
</dl>
</div>
<div class="variablelist">
<a id="search-api-response-body-score"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">_score</code>
</span>
</dt>
<dd>
(float)
Positive 32-bit floating point number used to determine the relevance of the
returned document.
</dd>
</dl>
</div>
<div class="variablelist">
<a id="search-api-response-body-source"></a>
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">_source</code>
</span>
</dt>
<dd>
<p>
(object)
Original JSON body passed for the document at index time.
</p>
<p>You can use the <code class="literal">_source</code> parameter to exclude this property from the response
or specify which source fields to return.</p>
</dd>
<dt>
<span class="term">
<code class="literal">fields</code>
</span>
</dt>
<dd>
<p>(object)
Contains field values for the documents. These fields must be specified in the
request using one or more of the following request parameters:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a class="xref" href="search-search.html#search-docvalue-fields-param"><code class="literal">docvalue_fields</code></a>
</li>
<li class="listitem">
<a class="xref" href="search-request-body.html#request-body-search-script-fields" title="Script Fields"><code class="literal">script_fields</code></a>
</li>
<li class="listitem">
<a class="xref" href="search-request-body.html#request-body-search-stored-fields" title="Stored Fields"><code class="literal">stored_fields</code></a>
</li>
</ul>
</div>
<p>This property is returned only if one or more of these parameters are set.</p>
<details open>
<summary class="title">Properties of <code class="literal">fields</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;field&gt;</code>
</span>
</dt>
<dd>
(array)
Key is the field name. Value is the value for the field.
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-search-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="search-api-specific-ex"></a>Search an index using the <code class="literal">q</code> query parameter<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h4>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /twitter/_search?q=user:kimchy</pre>
</div>
<div class="console_widget" data-snippet="snippets/1890.console"></div>
<p>The API returns the following response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "twitter",
        "_type" : "_doc",
        "_id": "0",
        "_score": 1.3862942,
        "_source": {
          "date": "2009-11-15T14:12:12",
          "likes": 0,
          "message": "trying out Elasticsearch",
          "user": "kimchy"
        }
      }
    ]
  }
}</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="search-multi-index"></a>Search several indices using the <code class="literal">q</code> query parameter<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h4>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /kimchy,elasticsearch/_search?q=user:kimchy</pre>
</div>
<div class="console_widget" data-snippet="snippets/1891.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="search-api-all-ex"></a>Search all indices using the <code class="literal">q</code> query parameter<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h4>
</div></div></div>
<p>To search all indices in a cluster,
omit the <code class="literal">&lt;index&gt;</code> parameter.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search?q=user:kimchy</pre>
</div>
<div class="console_widget" data-snippet="snippets/1892.console"></div>
<p>Alternatively,
you can use the <code class="literal">_all</code> or <code class="literal">*</code> value in the <code class="literal">&lt;index&gt;</code> parameter.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_all/_search?q=user:kimchy</pre>
</div>
<div class="console_widget" data-snippet="snippets/1893.console"></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /*/_search?q=user:kimchy</pre>
</div>
<div class="console_widget" data-snippet="snippets/1894.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="search-request-body-api-example"></a>Search an index using the <code class="literal">query</code> request body parameter<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search.asciidoc">edit</a>
</h4>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /twitter/_search
{
  "query": {
    "term": {
      "user": "kimchy"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1895.console"></div>
<p>The API returns the following response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "twitter",
        "_type" : "_doc",
        "_id": "0",
        "_score": 1.3862942,
        "_source": {
          "user": "kimchy",
          "message": "trying out Elasticsearch",
          "date": "2009-11-15T14:12:12",
          "likes": 0
        }
      }
    ]
  }
}</pre>
</div>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search.html">« Search APIs</a>
</span>
<span class="next">
<a href="search-request-body.html">Request Body Search »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>